home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 February / EnigmA AMIGA RUN 15 (1997)(G.R. Edizioni)(IT)[!][issue 1997-02][PLANET CD V].iso / enigma / earcd / sviluppo / svilupp2 / gmsppr10.lha / gamesupport.doc < prev    next >
Text File  |  1996-10-15  |  23KB  |  798 lines
  1. TABLE OF CONTENTS
  2.  
  3. gamesupport.library/--background--
  4. gamesupport.library/GS_AllocateColors
  5. gamesupport.library/GS_AllocateJoystick
  6. gamesupport.library/GS_DateWidth
  7. gamesupport.library/GS_DrawDate
  8. gamesupport.library/GS_DrawString
  9. gamesupport.library/GS_FormatDate
  10. gamesupport.library/GS_FormatString
  11. gamesupport.library/GS_FreeColors
  12. gamesupport.library/GS_FreeJoystick
  13. gamesupport.library/GS_FreeSprites
  14. gamesupport.library/GS_HappyBlanker
  15. gamesupport.library/GS_InsertScore
  16. gamesupport.library/GS_LoadSprites
  17. gamesupport.library/GS_MemoryAlloc
  18. gamesupport.library/GS_MemoryFree
  19. gamesupport.library/GS_MemoryRealloc
  20. gamesupport.library/GS_NoHappyBlanker
  21. gamesupport.library/GS_ObtainScoreHandle
  22. gamesupport.library/GS_ObtainScores
  23. gamesupport.library/GS_ReleaseScoreHandle
  24. gamesupport.library/GS_ReleaseScores
  25. gamesupport.library/GS_SendJoystick
  26. gamesupport.library/GS_StringWidth
  27. gamesupport.library/GS_TransformUsername
  28. gamesupport.library/GS_WindowSleep
  29. gamesupport.library/GS_WindowWakeup
  30. gamesupport.library/--background--         gamesupport.library/--background--
  31.  
  32.     gamesupport.library offsers various functions for
  33.     system-compliant, AUISG conforming games.
  34.  
  35.     Some things should be noted:
  36.     a) don't access gamesupport.library-maintained files (such
  37.        as high score tables) yourself. gamesupport.library uses
  38.        various locking techniques to ensure proper operation
  39.        with respect to multitasking and networked filesystems.
  40.  
  41.     b) gamesupport.library uses various assigns to let the user
  42.        override the default location for files. However,
  43.        strange (although not fatal with respect to overall system
  44.        operation) things might happen if you change these
  45.        assigns "in the middle of a game". The intended usage
  46.        is to setup any required assigns at boottime.
  47.  
  48.     c) currently AmigaOS V39 (Release 3.0) or newer is required
  49.  
  50.     d) there is no gamesupport memhandler. This is because you
  51.        cannot call FreePooled() on a shared memory pool (as used
  52.        by gamesupport.library) inside a memhandler. One of the
  53.        many AmigaOS design problems.
  54.  
  55.     e) gamesupport library ignores the starvation problem.
  56.  
  57. gamesupport.library/GS_AllocateColors   gamesupport.library/GS_AllocateColors
  58.  
  59.    NAME
  60.     GS_AllocateColors -- allocate colors in a screen.
  61.  
  62.    SYNOPSIS
  63.     Success = GS_AllocateColors(Screen, Colors, Distinct)
  64.       d0                          a0       a1       d0
  65.  
  66.     ULONG GS_AllocateColors(struct Screen *,struct GS_ColorDef *,ULONG);
  67.  
  68.    FUNCTION
  69.     Allocate the shared pens required for your program. You pass in
  70.     a table of RGB values, and you get a table of pens to use.
  71.     GS_AllocateColors() attempts to optimize the color search; so the
  72.     result is different from that of a normal for-loop.
  73.     We must call GS_FreeColors() when we're done with the pens.
  74.  
  75.    INPUTS
  76.     Screen     - the screen we want to open on
  77.     Colors     - the Red, Green and Blue fields must be set by you; they
  78.                  will remain unchanged.
  79.     Distinct   - how many distinct colors to get at most. Pass 0 for
  80.                  no limit.
  81.  
  82.    RESULT
  83.     Success - TRUE if everything went okay. Colors->DistinctColors
  84.               will be filled in for you.
  85.               If FALSE, you can check IoErr(): it returns 0 if we were
  86.               unable to allocate some or all pens.
  87.  
  88.     NOTE
  89.     The algorithm has been taken from Xmris 4.02.
  90.  
  91.    SEE ALSO
  92.     graphics.library/ObtainBestPen(), GameSupport.h, GS_FreeColors()
  93.  
  94. gamesupport.library/GS_AllocateJoystickamesupport.library/GS_AllocateJoystick
  95.  
  96.    NAME
  97.     GS_AllocateJoystick -- allocate the joystick
  98.  
  99.    SYNOPSIS
  100.     success = GS_AllocateJoystick(ReplyPort,ControllerType)
  101.        d0                            a0           d0
  102.  
  103.     ULONG GS_AllocateJoystick(struct MsgPort *, UBYTE);
  104.  
  105.    FUNCTION
  106.     Allocate gameport 1 by assigning it the specified controller
  107.     type.
  108.     If you allocate GPCT_ABSJOYSTICK, the trigger will be set
  109.     to report all joystick events and no timeouts.
  110.     You can use GameSupportBase->Joystick.Request and
  111.     GameSupportBase->Joystick.Event to access the controller.
  112.  
  113.    INPUTS
  114.     ReplyPort      - the port to use for the device I/O
  115.     ControllerType - the controller type (see <devices/gameport.h>)
  116.  
  117.    RESULT
  118.     success - TRUE if you got the joystick. FALSE if someone else
  119.         still owns it. You might want to try again later.
  120.  
  121.    SEE ALSO
  122.     GS_FreeJoystick(), GS_SendJoystick(), <devices/gameport.h>
  123.  
  124. gamesupport.library/GS_DateWidth             gamesupport.library/GS_DateWidth
  125.  
  126.     NAME
  127.     GS_DateWidth -- measure pixel width of a date
  128.  
  129.     SYNOPSIS
  130.     Width = GS_DateWidth(Template, TimeStamp, RastPort, Locale)
  131.      d0                    a0          d0        a1       a2
  132.  
  133.     WORD GS_DateWidth(const char *, ULONG, struct RastPort *,
  134.                       const struct Locale *);
  135.  
  136.     FUNCTION
  137.     Measure the pixel width of a date.
  138.  
  139.     INPUTS
  140.     Template     - the formatting template for FormatDate()
  141.     TimeStamp    - the time/date
  142.     RastPort     - the destination rastport
  143.     Locale       - the locale to use
  144.  
  145.     NOTE
  146.     If Locale==NULL or locale.library could not be opened,
  147.     a builtin formatter will be used to format the date.
  148.     The following commands are supported by this formatter:
  149.     %a %A %b %B %c %C %d %D %e %h %H %I %m %M %n %p %q %Q
  150.     %r %R %S %t %T %w %x %X %y %Y
  151.  
  152. gamesupport.library/GS_DrawDate               gamesupport.library/GS_DrawDate
  153.  
  154.     NAME
  155.     GS_DrawDate -- draw a date into a rastport
  156.  
  157.     SYNOPSIS
  158.     GS_DrawString(Template, TimeStamp, RastPort, Locale)
  159.                     a0          d0        a1       a2
  160.  
  161.     void GS_DrawDate(const char *, ULONG, struct RastPort *,
  162.                      const struct Locale *);
  163.  
  164.     FUNCTION
  165.     Draw a date into a rastport.
  166.  
  167.     INPUTS
  168.     Template     - the formatting template for FormatDate()
  169.     TimeStamp    - the time/date
  170.     RastPort     - the destination rastport
  171.     Locale       - the locale to use
  172.  
  173.     NOTE
  174.     If Locale==NULL or locale.library could not be opened,
  175.     a builtin formatter will be used to format the date.
  176.     The following commands are supported by this formatter:
  177.     %a %A %b %B %c %C %d %D %e %h %H %I %m %M %n %p %q %Q
  178.     %r %R %S %t %T %w %x %X %y %Y
  179.  
  180. gamesupport.library/GS_DrawString           gamesupport.library/GS_DrawString
  181.  
  182.     NAME
  183.     GS_DrawString -- draw a string into a rastport
  184.  
  185.     SYNOPSIS
  186.     GS_DrawString(Template, Parameters, RastPort, Locale)
  187.                     a0          a1        a2        a3
  188.  
  189.     void GS_DrawString(const char *, const void *, struct RastPort *,
  190.                        const struct Locale *);
  191.  
  192.     FUNCTION
  193.     Draw a string into a rastport, using a formatting template.
  194.  
  195.     INPUTS
  196.     Template     - the formatting template for FormatString()
  197.     Parameters   - the parameter list
  198.     RastPort     - the destination rastport
  199.     Locale       - the locale to use
  200.  
  201.     NOTE
  202.     If Locale==NULL or locale.library could not be opened,
  203.     RawDoFmt() will be used to format the string.
  204.  
  205. gamesupport.library/GS_FormatDate           gamesupport.library/GS_FormatDate
  206.  
  207.     NAME
  208.     GS_FormatDate -- FormatDate() with unlimited string size
  209.  
  210.     SYNOPSIS
  211.     String = GS_FormatDate(Template, TimeStamp, Length, Locale)
  212.       d0                      a0         d0       a1      a2
  213.  
  214.     char *GS_FormatDate(const char *, ULONG, ULONG *,
  215.                         const struct Locale *);
  216.  
  217.     FUNCTION
  218.     This function prints a date/time to a string.
  219.  
  220.     INPUTS
  221.     Locale    - A pointer to a locale
  222.     Template  - A format string for FormatDate()
  223.     TimeStamp - The date/time to output
  224.  
  225.     NOTE
  226.     If Locale==NULL or locale.library could not be opened,
  227.     a builtin formatter will be used to format the date.
  228.     The following commands are supported by this formatter:
  229.     %a %A %b %B %c %C %d %D %e %h %H %I %m %M %n %p %q %Q
  230.     %r %R %S %t %T %w %x %X %y %Y
  231.  
  232.     RESULT
  233.     String - the resulting string, or NULL if not enough memory.
  234.              Call GS_MemoryFree() to free the string.
  235.  
  236. gamesupport.library/GS_FormatString       gamesupport.library/GS_FormatString
  237.  
  238.     NAME
  239.     GS_FormatString -- sprintf() with unlimited string size
  240.  
  241.     SYNOPSIS
  242.     String = GS_FormatString(FormatString, Parameters, Length, Locale)
  243.       d0                         a0            a1        a2      a3
  244.  
  245.     char *GS_FormatString(const char *, const void *, ULONG *,
  246.                           const struct Locale *);
  247.  
  248.     FUNCTION
  249.     This function works like sprintf(), but it creates it's own
  250.     string. Therefore the length of the resulting string is not
  251.     limited.
  252.  
  253.     INPUTS
  254.     FormatString - A format string for FormatString()
  255.     Parameters   - The parameter list
  256.     Length       - Optional pointer to an ULONG receiving strlen()
  257.     Locale       - A pointer to a locale
  258.  
  259.     NOTE
  260.     If Locale==NULL or locale.library could not be opened,
  261.     RawDoFmt() will be used to format the string.
  262.  
  263.     RESULT
  264.     String - the resulting string, or NULL if not enough memory.
  265.              Call GS_MemoryFree() to free the string.
  266.  
  267. gamesupport.library/GS_FreeColors           gamesupport.library/GS_FreeColors
  268.  
  269.    NAME
  270.     GS_FreeColors -- free pens after we've used them.
  271.  
  272.    SYNOPSIS
  273.     GS_FreeColors(Screen, Colors)
  274.                     a0      a1
  275.  
  276.     void GS_FreeColors(struct Screen *, struct GS_ColorDef *);
  277.  
  278.    FUNCTION
  279.     Free the pens allocated by GS_AllocateColors(). Make sure there's
  280.     no visible graphics with those pens still on the screen; the
  281.     usual thing is to close the window, then call GS_FreeColors(),
  282.     then unlock the screen.
  283.     You can call GS_FreeColors() as often as you want. You must not
  284.     call GS_FreeColors() on an array that had no GS_AllocateColors()
  285.     called on it.
  286.  
  287.    INPUTS
  288.     Screen     - the screen. Must be the same screen as used for
  289.                  GS_AllocateColors(), of course.
  290.     Colors     - the structure filled in by GS_AllocateColors()
  291.  
  292.    SEE ALSO
  293.     GS_AllocateColors(), graphics.library/ReleasePen()
  294.  
  295. gamesupport.library/GS_FreeJoystick       gamesupport.library/GS_FreeJoystick
  296.  
  297.    NAME
  298.     GS_FreeJoystick -- free the joystick
  299.  
  300.    SYNOPSIS
  301.     GS_FreeJoystick()
  302.  
  303.     void GS_FreeJoystick(void);
  304.  
  305.    FUNCTION
  306.     Free the joystick you have allocated with GS_AllocateJoystick().
  307.     This makes the joystick available for other programs to use.
  308.  
  309.    NOTE
  310.     You should only hold the joystick while your window is
  311.     active. Remember, this is a non shareable resource!
  312.     So, it seems reasonable to to adopt the idea of a window
  313.     having the focus to the joystick as well: as long as a
  314.     window has the focus, input is directed to that window.
  315.  
  316.     NOTE
  317.     The joystick is allocated on a per-task basis. The same task
  318.     that successfully called GS_AllocateJoystick must call
  319.     GS_FreeJoystick().
  320.  
  321.     NOTE
  322.     You may call this function even if you don't own the
  323.     joystick. In this case, nothing happens.
  324.  
  325.     SEE ALSO
  326.     GS_AllocateJoystick()
  327.  
  328. gamesupport.library/GS_FreeSprites         gamesupport.library/GS_FreeSprites
  329.  
  330.    NAME
  331.     GS_FreeSprites -- free sprites loaded with GS_LoadSprites
  332.  
  333.    SYNOPSIS
  334.     GS_FreeSprites(Sprites, Screen);
  335.                       a0      a1
  336.  
  337.     void GS_FreeSprites(struct GS_Sprites *, struct Screen *);
  338.  
  339.    FUNCTION
  340.     Free the sprites. Call this when you're done with them.
  341.     The recommended usage is to close the window first, to make
  342.     sure that the colors are no longer visible.
  343.  
  344.    INPUTS
  345.     Sprites - the sprites returned from GS_LoadSprites(). NULL
  346.               is valid.
  347.     Screen  - the screen that we used to allocate the sprites
  348.  
  349.    RESULT
  350.     More free memory. More free colors (possibly).
  351.  
  352. gamesupport.library/GS_HappyBlanker       gamesupport.library/GS_HappyBlanker
  353.  
  354.     NAME
  355.     GS_HappyBlanker -- keep a screenblanker happy
  356.  
  357.     SYNOPSIS
  358.     Success = GS_HappyBlanker()
  359.        d0
  360.  
  361.     ULONG GS_HappyBlanker(void);
  362.  
  363.     FUNCTION
  364.     Turn the happy blanker on.
  365.     This means that input events will be sent down the input stream
  366.     to make sure that a screenblanker doesn't suddenly blank the
  367.     screen.
  368.     Turn this on while playing. Turn it off in pause or demo mode.
  369.  
  370.     RESULT
  371.  
  372.     SEE ALSO
  373.     GS_NoHappyBlanker()
  374.  
  375. gamesupport.library/GS_InsertScore         gamesupport.library/GS_InsertScore
  376.  
  377.    NAME
  378.     GS_InsertScore -- insert a score into the score tables
  379.  
  380.    SYNOPSIS
  381.     Error = GS_InsertScore(ScoreHandle, Score)
  382.      d0                        a0         a1
  383.  
  384.     LONG GS_InsertScore(void *, struct GS_Score *);
  385.  
  386.    FUNCTION
  387.     Check if we want to insert the new score. If yes, insert
  388.     it. Basically, you are expected to call this function
  389.     whenever a game is finished --- we determine ourselves
  390.     whether we actually want to insert the score.
  391.  
  392.    INPUTS
  393.     ScoreHandle  - a handle describing the files
  394.     Score        - the new score to insert
  395.  
  396.    RESULT
  397.     Error - error code (0 for success)
  398.             In any case, the Score->Name and Score->TimeStamp
  399.             will be set.
  400.  
  401. gamesupport.library/GS_LoadSprites         gamesupport.library/GS_LoadSprites
  402.  
  403.    NAME
  404.     GS_LoadSprites -- load the sprites
  405.  
  406.    SYNOPSIS
  407.     Sprites = GS_LoadSprites(Gamename,Screen)
  408.        d0                       a0      a1
  409.  
  410.     GS_Sprites *GS_LoadSprites(const char *, struct Screen *);
  411.  
  412.    FUNCTION
  413.     Read a sprite file and return a set of bitmaps.
  414.  
  415.    INPUTS
  416.     Gamename     - the name of the game. GS_LoadSprites() will append
  417.                    ".sprites" to get the filename
  418.     Screen       - the screen that we want to open on.
  419.  
  420.    RESULT
  421.     Sprites - a pointer to a (read-only) structure containing
  422.               the colormap and the image/mask bitmaps.
  423.               If NULL, IoErr() will return more information.
  424.               If IoErr()>0, then it is a dos error. <0 means IFF error.
  425.  
  426.    NOTE
  427.     A normal sprite is returned as a friend-bitmap.
  428.     The mask is a friend-bitmap, too!
  429.  
  430.    NOTE
  431.     A sprite with no CMAP and depth 1 is not remapped. Instead,
  432.     only a BMF_STANDARD image is returned, so you can pass
  433.     this to BltTemplate().
  434.  
  435.     Sprites are not shared (because there is no IsFriendBitmap()
  436.     function).
  437.  
  438.     Sigh. I wish Commodore (or whoever owns the Amiga these days)
  439.     would finally redesign all these broken gfx calls.
  440.     graphics.library is not really something that you could
  441.     show around without being ashamed. :(
  442.  
  443. gamesupport.library/GS_MemoryAlloc         gamesupport.library/GS_MemoryAlloc
  444.  
  445.    NAME
  446.     GS_MemoryAlloc -- allocate a block of memory
  447.  
  448.    SYNOPSIS
  449.     Memory = GS_MemoryAlloc(Size)
  450.       d0                     d0
  451.  
  452.     void *GS_MemoryAlloc(ULONG);
  453.  
  454.    FUNCTION
  455.     Allocate a block of memory. You must call GS_MemoryFree() when
  456.     you don't need the memory any longer.
  457.  
  458.    INPUTS
  459.     Size - the size of the memory block. 0 will return NULL and
  460.         ERROR_BAD_NUMBER.
  461.  
  462.    RESULT
  463.     Memory - a pointer to the allocated memory, or NULL.
  464.        In case of NULL, IoErr() will be set.
  465.  
  466.    NOTE
  467.     This is different from malloc(). You are responsible for freeing
  468.     the block!
  469.  
  470.    SEE ALSO
  471.     GS_MemoryFree()
  472.  
  473. gamesupport.library/GS_MemoryFree           gamesupport.library/GS_MemoryFree
  474.  
  475.    NAME
  476.     GS_MemoryFree -- free a memory block.
  477.  
  478.    SYNOPSIS
  479.     GS_MemoryFree(Memory)
  480.                     a0
  481.  
  482.     void GS_MemoryFree(void *);
  483.  
  484.    FUNCTION
  485.     The memory block is returned to the pool.
  486.  
  487.    INPUTS
  488.     Memory - the memory block. Must have been allocated by
  489.         MemoryAlloc(). NULL is valid.
  490.  
  491.    SEE ALSO
  492.     GS_MemoryAlloc()
  493.  
  494. gamesupport.library/GS_MemoryRealloc     gamesupport.library/GS_MemoryRealloc
  495.  
  496.    NAME
  497.     GS_MemoryRealloc -- reallocate a block of memory
  498.  
  499.    SYNOPSIS
  500.     NewMemory = GS_MemoryRealloc(OldMemory,NewSize)
  501.        d0                           a0        d0
  502.  
  503.     void *GS_MemoryRealloc(void *, ULONG);
  504.  
  505.    FUNCTION
  506.     Reallocates a block of memory. This function will free the
  507.     block passed in, allocate a new one and copy the old contents
  508.     to the new block. If the new block is smaller, it copies as
  509.     much as will fit (the rest is lost). If the new block is larger,
  510.     the additional bytes are not initialized. If the new block has
  511.     the same size, why did you call GS_MemoryRealloc()??
  512.  
  513.    INPUTS
  514.     OldMemory - the old memory block. Must have been allocated by
  515.         GS_MemoryMalloc() or GS_MemoryRealloc(). NULL is valid:
  516.         GS_MemoryRealloc(NULL,Size) is equivalent to
  517.         GS_MemoryMalloc(Size).
  518.     NewSize   - the size of the new block. 0 is valid here; it will
  519.         return NULL and ERROR_BAD_NUMBER.
  520.  
  521.    RESULT
  522.     NewMemory - the new memory block. In case of NULL, the old
  523.         pointer is still valid and must still be freed; in case
  524.         of non-NULL, you must not use the old pointer anymore.
  525.  
  526.    SEE ALSO
  527.     GS_MemoryAlloc(), GS_MemoryFree(), realloc()
  528.  
  529. gamesupport.library/GS_NoHappyBlanker   gamesupport.library/GS_NoHappyBlanker
  530.  
  531.    NAME
  532.     GS_NoHappyBlanker -- turn the happy blanker off
  533.  
  534.    SYNOPSIS
  535.     GS_NoHappyBlanker()
  536.  
  537.     void GS_NoHappyBlanker(void);
  538.  
  539.    FUNCTION
  540.     Turn off the happy blanker.
  541.  
  542.    NOTE
  543.     Only call this if GS_HappyBlanker() returned success.
  544.  
  545.    SEE ALSO
  546.     GS_HappyBlanker()
  547.  
  548. gamesupport.library/GS_ObtainScoreHandleesupport.library/GS_ObtainScoreHandle
  549.  
  550.    NAME
  551.     GS_ObtainScoreHandle -- obtain a handle to access score files
  552.  
  553.    SYNOPSIS
  554.     ScoreHandle = GS_ObtainScoreHandle(ScoreDef, SubPath, UserName)
  555.          d0                              a0        a1        a2
  556.  
  557.     void *GS_ObtainScoreHandle(const struct GS_ScoreDef *, const char *,
  558.                                const char *);
  559.  
  560.    FUNCTION
  561.     Get a handle for later access to the score files
  562.  
  563.    INPUTS
  564.     ScoreDef    - an initialized GS_ScoreDef structure.
  565.     SubPath     - an optional path, which can be used if the
  566.                   game keeps several score files.
  567.     UserName    - the user name. NULL or "" specifies the
  568.                   generic ("unknown") user.
  569.  
  570.    RESULT
  571.     ScoreHandle - a handle to use with the other score functions.
  572.                   NULL for failure.
  573.  
  574.    NOTE
  575.     UserName and ScoreDef must remain valid and unchanged for the
  576.     lifespan of the handle.
  577.  
  578.    NOTE
  579.     The current search path is
  580.         GAMESTUFF:<GameName> scores/<SubPath/>
  581.         <GameName>:<GameName> scores/<SubPath/>
  582.         PROGDIR:<GameName> scores/<SubPath/>
  583.  
  584. gamesupport.library/GS_ObtainScores       gamesupport.library/GS_ObtainScores
  585.  
  586.     NAME
  587.     GS_ObtainScores -- obtain a score table
  588.  
  589.     SYNOPSIS
  590.     Scores = GS_ObtainScores(ScoreHandle,ScoreType)
  591.       d0                        a0         d0
  592.  
  593.     const GS_ScoreList *GS_ObtainScores(void *, ULONG);
  594.  
  595.     FUNCTION
  596.     Return a score table.
  597.  
  598.     INPUTS
  599.     ScoreHandle  - a handle describing the files
  600.     ScoreType    - the file type that we want to read
  601.  
  602.     RESULT
  603.     Scores - a (read-only) linked list of scores. NULL for no
  604.              scores.
  605.  
  606.     NOTE
  607.     This function cannot fail: if we can't read the new scores,
  608.     the old scores are returned instead. This is because the
  609.     only thing we can do with the scores is to display them,
  610.     and it's better to display old scores instead of no scores
  611.     at all.
  612.  
  613.     SEE ALSO
  614.     GS_ObtainScoreHandle(), GS_ReleaseScores()
  615.  
  616. gamesupport.library/GS_ReleaseScoreHandleupport.library/GS_ReleaseScoreHandle
  617.  
  618.    NAME
  619.     GS_ReleaseScoreHandle -- release a score handle
  620.  
  621.    SYNOPSIS
  622.     GS_ReleaseScoreHandle(ScoreHandle)
  623.                                a0
  624.  
  625.     void GS_ReleaseScoreHandle(void *);
  626.  
  627.    FUNCTION
  628.     Release a handle obtained from GS_ObtainScoreHandle().
  629.  
  630.    INPUTS
  631.     ScoreHandle - the score handle to release, or NULL
  632.  
  633. gamesupport.library/GS_ReleaseScores     gamesupport.library/GS_ReleaseScores
  634.  
  635.     NAME
  636.     GS_ReleaseScores -- release a score table
  637.  
  638.     SYNOPSIS
  639.     GS_ReleaseScores(ScoreHandle, Scores)
  640.                        a0           a1
  641.  
  642. gamesupport.library/GS_SendJoystick       gamesupport.library/GS_SendJoystick
  643.  
  644.     NAME
  645.     GS_SendJoystick -- send joystick request
  646.  
  647.     SYNOPSIS
  648.     GS_SendJoystick()
  649.  
  650.     void GS_SendJoystick(void);
  651.  
  652.     FUNCTION
  653.     Initialize the GameSupportBase->Joystick.Request request
  654.     as GPD_READEVENT and send it to the gameport device.
  655.     Basically, joystick handling works like this:
  656.  
  657.     GS_AllocateJoystick()
  658.     GS_SendJoystick()
  659.     while (..)
  660.       {
  661.         Wait until GameSupportBase->Joystick.Request arrives at
  662.           your ReplyPort
  663.         Process GameSupportBase->Joystick.Event
  664.         GS_SendJoystick()
  665.       }
  666.     AbortIO()
  667.     GS_FreeJoystick()
  668.  
  669. gamesupport.library/GS_StringWidth         gamesupport.library/GS_StringWidth
  670.  
  671.     NAME
  672.     GS_StringWidth -- measure pixel width of a string
  673.  
  674.     SYNOPSIS
  675.     Width = GS_StringWidth(Template, Parameters, RastPort, Locale)
  676.      d0                      a0          a1        a2        a3
  677.  
  678.     WORD GS_StringWidth(const char *, const void *, struct RastPort *,
  679.                         const struct Locale *);
  680.  
  681.     FUNCTION
  682.     Measure the width of the resulting string.
  683.  
  684.     INPUTS
  685.     Template     - the formatting template for FormatString()
  686.     Parameters   - the parameter list
  687.     RastPort     - the destination rastport
  688.     Locale       - the locale to use
  689.  
  690.     NOTE
  691.     If Locale==NULL or locale.library could not be opened,
  692.     RawDoFmt() will be used to format the string.
  693.  
  694. gamesupport.library/GS_TransformUsernameesupport.library/GS_TransformUsername
  695.  
  696.     NAME
  697.     GS_TransformUsername -- transform username to filename
  698.  
  699.     SYNOPSIS
  700.     Filename = GS_TransformUsername(Username,OldFilename)
  701.        d0                              a0         a1
  702.  
  703.     char *GS_TransformUsername(const char *, char *);
  704.  
  705.     FUNCTION
  706.     Transform a username into something that most filesystems
  707.     will accept as filename.
  708.     OldFilename is a Filename that was returned from this
  709.     function. If it is non-NULL, OldFilename will be freed
  710.     and a new filename will be returned.
  711.  
  712.     The intended use for this function is as follows:
  713.  
  714.     int Success;
  715.     char *Filename;
  716.  
  717.     Success=FALSE;
  718.     Filename=NULL;
  719.     while (!Success)
  720.       {
  721.         Filename=GS_TransformUsername(Username,Filename);
  722.         if (Filename==NULL)
  723.           Error();
  724.         File=OpenFile(Filename);
  725.            if (File does not exist)
  726.           Success=TRUE;
  727.         else
  728.           {
  729.             FileUsername=ReadUsernameFromFile();
  730.             if (FileUsername is equal to Username)
  731.               Success=TRUE;
  732.           }           
  733.       }
  734.  
  735.     Since the returned Filename is not unique, we read the
  736.     Username from the file to check whether we catched the
  737.     correct file. If we didn't, we just try the "next"
  738.     transformation.
  739.  
  740.     INPUTS
  741.     Username    - the name of the user
  742.     OldFilename - previous Filename, or NULL
  743.  
  744.     RESULT
  745.     Filename - a string to use as filename. NULL for error.
  746.                   Call GS_MemoryFree(Filename) when done.
  747.  
  748. gamesupport.library/GS_WindowSleep         gamesupport.library/GS_WindowSleep
  749.  
  750.     NAME
  751.     GS_WindowSleep -- put window to sleep
  752.  
  753.     SYNOPSIS
  754.     Success = GS_WindowSleep(Window)
  755.                               a0
  756.  
  757.     ULONG GS_WindowSleep(struct Window *);
  758.  
  759.     FUNCTION
  760.     Put window to sleep.
  761.  
  762.     INPUTS
  763.     Window - the window.
  764.  
  765.     RESULT
  766.     Success - TRUE for success (or for a NULL window)
  767.  
  768.     NOTE
  769.     There are two possible reasons for failure: not enough memory
  770.     available to allocate a requester structure, or the maximum
  771.     number of requesters in the window would be exceeded.
  772.  
  773.     SEE ALSO
  774.     GS_WindowWakeup()
  775.  
  776. gamesupport.library/GS_WindowWakeup       gamesupport.library/GS_WindowWakeup
  777.  
  778.     NAME
  779.     GS_WindowWakeup -- wakeup window
  780.  
  781.     SYNOPSIS
  782.     GS_WindowWakeup(Window)
  783.                       a0
  784.  
  785.     void GS_WindowWakeup(struct Window *);
  786.  
  787.     FUNCTION
  788.     Undo the effects of GS_WindowSleep().
  789.  
  790.     INPUTS
  791.     Window - the window
  792.  
  793.     NOTE
  794.     This function removes the Window->FristRequester requester
  795.     and GS_MemoryFree()s it. So you better make sure it's not
  796.     another requester...
  797.  
  798.